package modbus

// GatewayRawData 原始数据收发结构
type GatewayRawData struct {
	RequestADU  []byte // 请求ADU（完整的MBAP头+PDU）
	ResponseADU []byte // 响应ADU（完整的MBAP头+PDU）
	Error       error  // 错误信息（如果有）
}

// Client interface.
type Client interface {
	ClientProvider
	// Bits

	// ReadCoils reads from 1 to 2000 contiguous status of coils in a
	// remote device and returns coil status.
	ReadCoils(slaveID byte, address, quantity uint16) (results []byte, err error)
	// ReadDiscreteInputs reads from 1 to 2000 contiguous status of
	// discrete inputs in a remote device and returns input status.
	ReadDiscreteInputs(slaveID byte, address, quantity uint16) (results []byte, err error)

	// WriteSingleCoil write a single output to either ON or OFF in a
	// remote device and returns success or failed.
	WriteSingleCoil(slaveID byte, address uint16, isOn bool) error
	// WriteMultipleCoils forces each coil in a sequence of coils to either
	// ON or OFF in a remote device and returns success or failed.
	WriteMultipleCoils(slaveID byte, address, quantity uint16, value []byte) error

	// 16-bits

	// ReadInputRegistersBytes reads from 1 to 125 contiguous input registers in
	// a remote device and returns input registers.
	ReadInputRegistersBytes(slaveID byte, address, quantity uint16) (results []byte, err error)
	// ReadInputRegisters reads from 1 to 125 contiguous input registers in
	// a remote device and returns input registers.
	ReadInputRegisters(slaveID byte, address, quantity uint16) (results []uint16, err error)

	// ReadHoldingRegistersBytes reads the contents of a contiguous block of
	// holding registers in a remote device and returns register value.
	ReadHoldingRegistersBytes(slaveID byte, address, quantity uint16) (results []byte, err error)
	// ReadHoldingRegisters reads the contents of a contiguous block of
	// holding registers in a remote device and returns register value.
	ReadHoldingRegisters(slaveID byte, address, quantity uint16) (results []uint16, err error)

	// WriteSingleRegister writes a single holding register in a remote
	// device and returns success or failed.
	WriteSingleRegister(slaveID byte, address, value uint16) error
	// WriteMultipleRegistersBytes writes a block of contiguous registers
	// (1 to 123 registers) in a remote device and returns success or failed.
	WriteMultipleRegistersBytes(slaveID byte, address, quantity uint16, value []byte) error
	// WriteMultipleRegisters writes a block of contiguous registers
	// (1 to 123 registers) in a remote device and returns success or failed.
	WriteMultipleRegisters(slaveID byte, address, quantity uint16, value []uint16) error

	// ReadWriteMultipleRegistersBytes performs a combination of one read
	// operation and one write operation. It returns read registers value.
	ReadWriteMultipleRegistersBytes(slaveID byte, readAddress, readQuantity,
		writeAddress, writeQuantity uint16, value []byte) (results []byte, err error)
	// ReadWriteMultipleRegisters performs a combination of one read
	// operation and one write operation. It returns read registers value.
	ReadWriteMultipleRegisters(slaveID byte, readAddress, readQuantity,
		writeAddress, writeQuantity uint16, value []byte) (results []uint16, err error)

	// MaskWriteRegister modify the contents of a specified holding
	// register using a combination of an AND mask, an OR mask, and the
	// register's current contents. The function returns success or failed.
	MaskWriteRegister(slaveID byte, address, andMask, orMask uint16) error
	// ReadFIFOQueue reads the contents of a First-In-First-Out (FIFO) queue
	// of register in a remote device and returns FIFO value register.
	ReadFIFOQueue(slaveID byte, address uint16) (results []byte, err error)

	// Diagnostic Functions

	// ReadExceptionStatus returns the exception status of the remote device.
	// This function can quickly determine the status of the eight Exception Status outputs.
	ReadExceptionStatus(slaveID byte) (status byte, err error)

	// Diagnostics performs diagnostic testing on the remote device.
	// SubFunction codes define specific diagnostic tests to perform.
	Diagnostics(slaveID byte, subFunction uint16, data []byte) (results []byte, err error)

	// GetCommEventCounter returns the communication event counter and status.
	// This function provides access to a running count of communication events.
	GetCommEventCounter(slaveID byte) (status uint16, eventCount uint16, err error)

	// Device Identification Functions

	// ReportSlaveID returns device-specific information such as slave ID,
	// run status, and additional device identification data.
	ReportSlaveID(slaveID byte) (data []byte, err error)

	// ReadDeviceIdentification returns device identification information.
	// This function provides access to standard device identification objects.
	ReadDeviceIdentification(slaveID byte, readCode byte, objectID byte) (results []byte, err error)

	// Gateway Protocol Extension Functions

	// GatewayReadDataRecords reads 32 historical data records from gateway device.
	// timestamp: aligned timestamp from GatewayReadDataRecordsAlign
	// Returns 32 DataRecord structures (512 bytes total)
	GatewayReadDataRecords(slaveID byte, timestamp uint32) (records []*DataRecord, rawData GatewayRawData, err error)

	// GatewayReadCurrentData reads current real-time data from gateway device.
	// Returns a single 16-byte DataRecord with current device status
	GatewayReadCurrentData(slaveID byte) (record *DataRecord, rawData GatewayRawData, err error)

	// GatewayWriteSubDevParam writes sub-device (transmitter) parameter.
	// Only valid for Unit IDs 1-64 (transmitters)
	// paramAddr: parameter address (0x0001-0x000A)
	// paramValue: parameter value (must be within valid range)
	GatewayWriteSubDevParam(slaveID byte, paramAddr uint16, paramValue uint32) (rawData GatewayRawData, err error)

	// GatewayWriteGatewayParam writes gateway parameter.
	// Only valid for Unit IDs 65-247 (gateways)
	// paramAddr: parameter address (0x0001-0x0004)
	// paramValue: parameter value (must be within valid range)
	GatewayWriteGatewayParam(slaveID byte, paramAddr uint16, paramValue uint32) (rawData GatewayRawData, err error)

	// GatewayReadSubDevParam reads sub-device (transmitter) parameter.
	// Only valid for Unit IDs 1-64 (transmitters)
	// paramAddr: parameter address (0x0001-0x000A)
	// Returns the current parameter value
	GatewayReadSubDevParam(slaveID byte, paramAddr uint16) (paramValue uint32, rawData GatewayRawData, err error)

	// GatewayReadGatewayParam reads gateway parameter.
	// Only valid for Unit IDs 65-247 (gateways)
	// paramAddr: parameter address (0x0001-0x0004)
	// Returns the current parameter value
	GatewayReadGatewayParam(slaveID byte, paramAddr uint16) (paramValue uint32, rawData GatewayRawData, err error)
}
